Clarify docs about env "useBuiltIns" behavior and common uses. #2425
Conversation
|
Deploy preview for babel ready! Built without sensitive environment variables with commit 73289b7 |
|
|
||
| # or | ||
| Generally, `"usage"` meets the needs of most users by only including the polyfills that are needed. |
There was a problem hiding this comment.
This might be a tricky recommendation for users who have dependencies in node_modules that rely on certain built-ins being available that aren't run through Babel.
There was a problem hiding this comment.
I hadn't even considered that. Sounds like a nuance worth mentioning, I'll include that...
| @@ -264,18 +264,85 @@ This option is useful for "blacklisting" a transform like `@babel/plugin-transfo | |||
|
|
|||
| `"usage"` | `"entry"` | `false`, defaults to `false`. | |||
|
|
|||
| This option configures how `@babel/preset-env` handles polyfills. | |||
| This option configures how `@babel/preset-env` handles polyfills and whether optimizations are applied to only include polyfills that are needed. | |||
There was a problem hiding this comment.
What about something like:
| This option configures how `@babel/preset-env` handles polyfills and whether optimizations are applied to only include polyfills that are needed. | |
| This option configures `@babel/preset-env` to only include the polyfills needed by your target environment(s). This can either include all polyfills needed to mimic a ES2020 environment (`entry`), or only include polyfills as they are needed/used in each file (`usage`). |
There was a problem hiding this comment.
Riffing on that a bit more, how about this? I dropped mention of ES2020 because that will become outdated eventually.
| This option configures how `@babel/preset-env` handles polyfills and whether optimizations are applied to only include polyfills that are needed. | |
| This option configures `@babel/preset-env` to only include the polyfills needed by your target environment(s) to mimic the latest JS-spec environment. Options are to include polyfills as they are needed/used in each file (`usage`) or include polyfills at the entrypoint to your application (`entry`). |
Given the nuance you mention, I'm not exactly clear on what are the pros/cons of each? If usage wouldn't help people in the case about node_modules you mentioned above, is there a reason people wouldn't always just use entry? If I understand that aspect more, then I think we could get a better synopsis out to users.
There was a problem hiding this comment.
There are certainly people who do compile their node_modules (or if you're sure that your deps don't need to be polyfilled) to get the full benefit of usage, it's just a caveat that people may not be aware of when they're setting up Babel for their project.
There was a problem hiding this comment.
That totally makes sense. I'm just trying to understand, when you say "the full benefit of usage", what is that benefit? Are there benefits of usage over entry? I think that would be good to showcase.
I think a lot of people wind up at this section of the docs and can get pretty easily overwhelmed by all the details about polyfills, core-js, etc.
My intent was to provide some more language around how the system works, and what people "probably" will want to choose the majority of the time, to guide them in the right direction.
I also switched the order of the detailed sections on
usageandentryso that it reflects the order of the options presented (usage, entry, false).